<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="tutorial.css">
<TITLE>
How do I write an ECLiPSe program?
</TITLE>
</HEAD>
<BODY >
<A HREF="tutorial007.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="tutorial003.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="tutorial009.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc8">2.5</A>&nbsp;&nbsp;How do I write an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> program?</H2><UL>
<LI><A HREF="tutorial008.html#toc2">Compiling a program</A>
<LI><A HREF="tutorial008.html#toc3">Executing a query</A>
<LI><A HREF="tutorial008.html#toc4">Editing a file</A>
<LI><A HREF="tutorial008.html#toc5">Debugging a program</A>
<LI><A HREF="tutorial008.html#toc6">File menu</A>
<LI><A HREF="tutorial008.html#toc7">Getting help</A>
<LI><A HREF="tutorial008.html#toc8">Other tools</A>
</UL>

You need to use an editor to write your programs. ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> does not come
with an editor, but any editor that can save plain text files can be used. 
Save your program as a plain text file, and you can then compile the
program into ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> and run it.<BR>
<BR>
Extra support for editing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> programs with common editors are
available. An eclipse mode for the GNU emacs editor is bundled with the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> package. This mode provides syntax highlighting, automatic
indentation and many other features. To use this mode, you need to load the
<TT>eclipse.el</TT> file into emacs. This is done by adding the following
line to your <TT>.emacs</TT> file:<BR>
<BR>

<PRE CLASS="verbatim">
(autoload 'eclipse-mode "&lt;eclipsedir&gt;/lib_public/eclipse.el" "ECLIPSE editing mode" t)
</PRE>
where <TT>&lt;eclipsedir&gt;</TT> is the path to your ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> installation
directory. <BR>
<BR>
With TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, you can specify the editor you want to use, and this
editor will be started by TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, e.g. when you select a file in
the `Edit' option under the File menu. The default values are the value of
the VISUAL environment variable under Unix, or Wordpad under Windows.
This can be changed with the Preference Editor under the Tools menu.<BR>
<BR>
<A NAME="toc2"></A>
<H3 CLASS="subsection"><A NAME="htoc9">2.5.1</A>&nbsp;&nbsp;Compiling a program</H3>
<A NAME="@default0"></A>
From the <TT>File</TT> menu, select the <TT>Compile ...</TT> option.
This will bring up a file selection dialogue. Select the file you wish
to compile, and click on the <TT>Open</TT> button. This will compile
the file and any others it depends on. Messages indicating which
files have been compiled and describing any errors encountered will be
displayed in the bottom portion of the TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> window
(<TT>Output and Error Messages</TT>).<BR>
<BR>
If a file has been modified since it was compiled, it may be
recompiled by clicking on the <TT>make</TT> button. This recompiles
any files which have become out-of-date.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>&#8857;</B><DD CLASS="dd-description"> <FONT COLOR="#9832CC">For more information on program compilation and the compiler,
please see <B>The Compiler</B> chapter in the user manual.</FONT>
</DL>

<A NAME="toc3"></A>
<H3 CLASS="subsection"><A NAME="htoc10">2.5.2</A>&nbsp;&nbsp;Executing a query</H3>
<A NAME="@default1"></A>
To execute a query, first enter it into the <TT>Query Entry</TT> text
field. You will also need to specify which module the query should be
run from, by selecting the appropriate entry from the drop-down list
to the left of the <TT>Query Entry</TT> field. Normally, the default
selection of <TT>eclipse</TT> will be fine; this will allow access to
all ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> built-ins and all predicates that have not explicitly
been compiled into a different module. Selecting another module for
the query is only needed if you wish to call a predicate which is not
visible from the <TT>eclipse</TT> module, in which case you need to
select that module. 
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>&#8857;</B><DD CLASS="dd-description"> <FONT COLOR="#9832CC">For more information about the module
system, please see the <B>Module System</B> chapter in the user
manual.</FONT>
</DL>

To actually execute the query, either hit the <TT>Enter</TT> key
while editing the query, or click on the <TT>run</TT> button.
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> maintains a history of commands entered during the
session, and these may be recalled either by using the drop-down list
to the right of the <TT>Query Entry</TT> field, or by using the up
and down arrow keys while editing the <TT>Query Entry</TT> field.<BR>
<BR>
If ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> cannot find a solution to the query, it will print
<TT>No</TT> in the <TT>Results</TT> section of the TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
window. If it finds a solution and knows there are no more, it will
print it in the <TT>Results</TT> section, and then print
<TT>Yes</TT>. If it finds a solution and there may be more, it will
print the solution found as before, print <TT>More</TT>, and enable
the <TT>more</TT> button. Clicking on the <TT>more</TT> button
tells ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to try to find another solution. In all cases it
also prints the total time taken to execute the query.<BR>
<BR>
From <TT>Query</TT> menu, you can run the query with various analysis tools
(see chapter&nbsp;<A HREF="tutorial042.html#sec:program-analysis">6</A>): <TT>Time Profile</TT> option
will run the query with the profiler tool; <TT>Port Profile</TT> option
will run the query with the port profiler tool. <BR>
<BR>
Note that a query can be interrupted during execution by clicking on
the <TT>interrupt</TT> button.<BR>
<BR>
<A NAME="toc4"></A>
<H3 CLASS="subsection"><A NAME="htoc11">2.5.3</A>&nbsp;&nbsp;Editing a file</H3>
<A NAME="secedit"></A>
If you wish to edit a file (e.g. a program source file), then you may
do so by selecting the <TT>Edit ...</TT> option from the
<TT>File</TT> menu (or use the <TT>Edit new ...</TT> option if the file
does not yet exist). This will bring up a file selection dialogue.
Select the file you wish to edit, and click on the <TT>Open</TT>
button.<BR>
<BR>
When you have finished editing the file, save it. After you've saved
it, if you wish to update the version compiled into ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
(assuming it had been compiled previously), simply click on the
<TT>make</TT> button.<BR>
<BR>
You can change which program is used to edit your file by using the
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> Preference Editor, available from the <TT>Tools</TT>
menu. Alternatively you can use your editor separately from
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.<BR>
<BR>
<A NAME="toc5"></A>
<H3 CLASS="subsection"><A NAME="htoc12">2.5.4</A>&nbsp;&nbsp;Debugging a program</H3>
<A NAME="secdebug"></A>
To help diagnose problems in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> programs, TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
provides the tracer. It is activated by selecting the
<TT>Tracer</TT> option from the <TT>Tools</TT> menu. The next time
a goal is executed, the tracer window will become active, allowing you
to step through the program's execution and examine the program's
state as it executes. A full example is given in
chapter&nbsp;<A HREF="tutorial037.html#chapdebug">5</A>.<BR>
<BR>
<A NAME="toc6"></A>
<H3 CLASS="subsection"><A NAME="htoc13">2.5.5</A>&nbsp;&nbsp;File menu</H3>
The <TT>File</TT> menu of TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> provides various options to
manipulate files:<BR>
<BR>

<H4 CLASS="subsubsection">Compile</H4> 
Allows the user to select a file to compile into ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. <BR>
<BR>

<H4 CLASS="subsubsection">Use module</H4>
Allows the user to select and load an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> module file into
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>.<BR>
<BR>

<H4 CLASS="subsubsection">Edit</H4> 
Allows the user to select a file to edit using the default text editor 

<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>&#8857;</B><DD CLASS="dd-description"> <FONT COLOR="#9832CC">See section&nbsp;</FONT><A HREF="#secedit"><FONT COLOR="#9832CC">2.5.3</FONT></A><FONT COLOR="#9832CC"> for more information on editors.</FONT>
</DL>
.<BR>
<BR>

<H4 CLASS="subsubsection">Edit new</H4>
Allows the user to specify a new file that will be opened with the default
text editor.<BR>
<BR>

<H4 CLASS="subsubsection">Cross referencer</H4>
Allows the user to select an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> source file and produce a cross
reference over it, and display the resulting graph in a new window.<BR>
<BR>

<H4 CLASS="subsubsection">Change directory</H4>
Allows the user to change the current working directory.<BR>
<BR>

<H4 CLASS="subsubsection">Change to example directory</H4>
Change the current working directory to the example directory in the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> distribution.<BR>
<BR>

<H4 CLASS="subsubsection">New module</H4>
Allows the user to specify a new module that will be created. The new
module becomes the current toplevel module. <BR>
<BR>

<H4 CLASS="subsubsection">Clear toplevel module</H4> 
Allows the user to clear the current toplevel module, i.e. to erase it and
start with a fresh, empty module.<BR>
<BR>

<H4 CLASS="subsubsection">Exit</H4>
 Leave ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP><BR>
<BR>
<A NAME="toc7"></A>
<H3 CLASS="subsection"><A NAME="htoc14">2.5.6</A>&nbsp;&nbsp;Getting help</H3>
<A NAME="@default2"></A>
More detailed help than is provided here can be obtained online for
all the features of TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. Simply select the entry from the
<TT>Help</TT> menu on TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>'s top-level window which
corresponds to the topic or tool you are interested in.<BR>
<BR>
Detailed documentation about all the predicates in the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> libraries can be obtained through the
<TT>Library Browser and Help</TT> tool.
This tool allows you to browse the online help for the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
libraries. On the left is a tree display of the libraries available
and the predicates they provide.
<UL CLASS="itemize"><LI CLASS="li-itemize">
Double clicking on a node in this tree either expands it or
collapses it again.
<LI CLASS="li-itemize">Clicking on an entry displays help for that entry to the right.
<LI CLASS="li-itemize">Double clicking on a word in the right-hand pane searches for
help entries containing that string.
</UL>
You can also enter a search string or a predicate specification
manually in the text entry box at the top right. If there is only one
match, detailed help for that predicate is displayed. If there are
multiple matches, only very brief help is displayed for each; to get
detailed help, try specifying the module and/or the arity of the
predicate in the text field.<BR>
<BR>
Alternatively, you can call the help/1 predicate in the query window
(which contains the same information as the HTML Reference Manual).
It has two modes of operation. First, when a fragment of a built-in
name is specified, a list of short descriptions of all built-ins whose
name contains the specified string is printed. For example,
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
?- help(write).
</PRE></BLOCKQUOTE>
will print one-line descriptions about <B><TT>write/1</TT></B>, <B><TT>writeclause/2</TT></B>, etc. When a unique specification is given, the full
description of the specified built-in is displayed, e.g. in
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
?- help(write/1).
</PRE></BLOCKQUOTE>
or
<BLOCKQUOTE CLASS="quote">
<PRE CLASS="verbatim">
?- help(ic:alldifferent/1).
</PRE></BLOCKQUOTE>
<A NAME="toc8"></A>
<H3 CLASS="subsection"><A NAME="htoc15">2.5.7</A>&nbsp;&nbsp;Other tools</H3>
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> comes with a number of useful tools. Some have been
mentioned above, but here is a more complete list. Note that we only
provide brief descriptions here; for more details, please see the
online help for the tool in question.<BR>
<BR>

<H4 CLASS="subsubsection">Compile scratch-pad</H4>
This tool allows you to enter small amounts of program code and have
it compiled. This is useful for quick experimentation, but not for
larger examples or programs you wish to keep, since the source code is
lost when the session is exited.<BR>
<BR>

<H4 CLASS="subsubsection">Source File Manager</H4>
This tool allows you to keep track of and manage which source files
have been compiled in the current ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> session. You can select
files to edit them, or compile them individually, as well as adding
new files.<BR>
<BR>

<H4 CLASS="subsubsection">Predicate Browser</H4>
This tool allows you to browse through the modules and predicates
which have been compiled in the current session. It also lets you
alter some properties of compiled predicates.<BR>
<BR>

<H4 CLASS="subsubsection">Source Viewer</H4>
This tool attempts to display the source code for predicates selected
in other tools.<BR>
<BR>

<H4 CLASS="subsubsection">Delayed Goals</H4>
This tool displays the current delayed goals, as well as allowing a
spy point to be placed on the predicate and the source code viewed.<BR>
<BR>

<H4 CLASS="subsubsection">Inspector</H4>
This tool provides a graphical browser for inspecting terms. Goals
and data terms are displayed as a tree structure. Sub-trees can be
collapsed and expanded by double-clicking. A navigation panel can be
launched which provides arrow buttons as an alternative way to
navigate the tree.<BR>
<BR>
Note that while the inspector window is open, interaction with other
TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> windows is disallowed. This prevents the term from
changing while being inspected. To continue TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, the
inspector window must be closed.<BR>
<BR>

<H4 CLASS="subsubsection">Visualisation Client</H4>
This starts a new Java visualisation client that allows ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> programs
to be visualised with the visualisation tools. See the Visualisation manual
for details on the visualisation tools.<BR>
<BR>

<H4 CLASS="subsubsection">Global Settings</H4>
This tool allows the setting of some global flags governing the way
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> behaves. See also the documentation for the
<A HREF="../bips/kernel/env/set_flag-2.html"><B>set_flag/2</B></A><A NAME="@default3"></A> and
<A HREF="../bips/kernel/env/get_flag-2.html"><B>get_flag/2</B></A><A NAME="@default4"></A> predicates.<BR>
<BR>

<H4 CLASS="subsubsection">Statistics</H4>
This tool displays some statistics about memory and CPU usage of the
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> system, updated at regular intervals. See also the
documentation for the
<A HREF="../bips/kernel/env/statistics-0.html"><B>statistics/0</B></A><A NAME="@default5"></A> and
<A HREF="../bips/kernel/env/statistics-2.html"><B>statistics/2</B></A><A NAME="@default6"></A>
predicates.<BR>
<BR>

<H4 CLASS="subsubsection">Preference Editor</H4>
This tool allows you to edit and set various user preferences. This
include parameters for how TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> will start up, e.g. the amount
of memory it will be able to use, and a initial query to execute; and
parameters which affects the appearance of TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>, such as the
fonts TkECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> uses and which editor it launches.<BR>
<BR>
<HR>
<A HREF="tutorial007.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="tutorial003.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="tutorial009.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
